schema gen support starlight migration#6119
Conversation
✅ Deploy Preview for esphome ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
WalkthroughA single file Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Tip Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@script/schema_doc.py`:
- Around line 29-30: SeeAlso.md() and convert_links_and_shortcodes are building
URLs by slicing path.parts[1:-1], which breaks when DOCS_ROOT has extra path
segments; change both to compute the path relative to DOCS_ROOT (use
Path.relative_to(DOCS_ROOT) or Path.resolve().relative_to(DOCS_ROOT.resolve()))
and build the URL from that relative path's parts (remove the file suffix and
join remaining parts with '/'), replacing the hardcoded parts[1:-1] logic so
generated URLs are relative to DOCS_ROOT regardless of its depth.
- Around line 407-416: The fallback lookup currently checks for "_index.mdx" and
the guards compare file_name == "_index", but the repo uses "index.mdx" so these
branches never match; update the fallback in the ref resolution (variable
ref_md_default) to look for ref / "index.mdx" (and the DOCS_ROOT components
fallback to (ref + ".mdx") remains), and change the guards that compare
file_name == "_index" to compare file_name == "index" (search for uses of
md_file.stem and the variables file_name around the checks at the two locations)
so directory index pages are detected correctly.
| DOCS_ROOT = Path(".") / "src" / "content" / "docs" | ||
|
|
There was a problem hiding this comment.
URL generation in SeeAlso.md() and convert_links_and_shortcodes is broken by the new path depth.
DOCS_ROOT now resolves to PosixPath("src/content/docs") (3 parts), so doc files have paths like src/content/docs/components/sensor.mdx with parts ('src', 'content', 'docs', 'components', 'sensor.mdx').
Both SeeAlso.md() (line 75) and convert_links_and_shortcodes (line 452) use the hardcoded parts[1:-1] slice, which was designed for a 1-level prefix (content/):
| Structure | parts[1:-1] |
Generated URL |
|---|---|---|
Old: content/components/sensor.md |
('components',) |
/components/sensor ✓ |
New: src/content/docs/components/sensor.mdx |
('content', 'docs', 'components') |
/content/docs/components/sensor ✗ |
This will cause all "See also" links and relative docref shortcode URLs written into the schema JSON to be incorrect. Fix by making the URL slice relative to DOCS_ROOT:
🐛 Proposed fix — derive URL relative to `DOCS_ROOT`
Apply to SeeAlso.md() (line 75):
def md(self):
- url_path = "/" + "/".join(list(self.file.parts[1:-1]))
- if self.file.stem != "_index":
- url_path += f"/{self.file.stem}"
+ relative = self.file.relative_to(DOCS_ROOT)
+ url_path = "/" + "/".join(relative.parts[:-1])
+ if self.file.stem not in ("_index", "index"):
+ url_path += f"/{self.file.stem}"Apply to convert_links_and_shortcodes (line 452):
- url = args.deploy_url + "/" + "/".join(md_file.parts[1:-1]) + "/" + ref
+ url = args.deploy_url + "/" + "/".join(md_file.relative_to(DOCS_ROOT).parts[:-1]) + "/" + ref🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@script/schema_doc.py` around lines 29 - 30, SeeAlso.md() and
convert_links_and_shortcodes are building URLs by slicing path.parts[1:-1],
which breaks when DOCS_ROOT has extra path segments; change both to compute the
path relative to DOCS_ROOT (use Path.relative_to(DOCS_ROOT) or
Path.resolve().relative_to(DOCS_ROOT.resolve())) and build the URL from that
relative path's parts (remove the file suffix and join remaining parts with
'/'), replacing the hardcoded parts[1:-1] logic so generated URLs are relative
to DOCS_ROOT regardless of its depth.
| ref_md_path = md_parent / (ref + ".mdx") | ||
| if ref_md_path.exists(): | ||
| return ref_md_path | ||
| ref_md_default = md_parent / ref / "_index.md" | ||
| ref_md_default = md_parent / ref / "_index.mdx" | ||
| if ref_md_default.exists(): | ||
| return ref_md_default | ||
| ref_md_default = Path(".") / "content" / "components" / (ref + ".md") | ||
| ref_md_default = DOCS_ROOT / "components" / (ref + ".mdx") | ||
| if ref_md_default.exists(): | ||
| return ref_md_default | ||
| return md_file # go nowhere |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Check the actual MDX files in the docs structure
find src/content/docs -type f -name "*index.mdx" 2>/dev/null | head -30Repository: esphome/esphome-docs
Length of output: 1439
🏁 Script executed:
# Check for _index.mdx files specifically
find src/content/docs -type f -name "_index.mdx" 2>/dev/null | head -30Repository: esphome/esphome-docs
Length of output: 46
🏁 Script executed:
# Get context around lines 407-416, 765, and 787 in script/schema_doc.py
sed -n '400,420p' script/schema_doc.pyRepository: esphome/esphome-docs
Length of output: 662
🏁 Script executed:
# Check line 765 context
sed -n '760,770p' script/schema_doc.pyRepository: esphome/esphome-docs
Length of output: 449
🏁 Script executed:
# Check line 787 context
sed -n '780,795p' script/schema_doc.pyRepository: esphome/esphome-docs
Length of output: 827
🏁 Script executed:
# Search for where file_name is assigned before line 787
sed -n '700,790p' script/schema_doc.py | grep -n "file_name"Repository: esphome/esphome-docs
Length of output: 218
🏁 Script executed:
# Get broader context around the file processing loop
sed -n '680,810p' script/schema_doc.pyRepository: esphome/esphome-docs
Length of output: 4850
Update _index.mdx references to index.mdx — Hugo migration incomplete.
The codebase uses index.mdx for directory index files (confirmed across src/content/docs/), but the fallback lookup at line 410 still searches for _index.mdx, which no longer exists. Similarly, the guards at lines 787 and 797 check file_name == "_index", but file_name = md_file.stem will be index for actual files, so these conditions never match.
Update all three locations to use the index convention:
Proposed fixes
Line 410:
- ref_md_default = md_parent / ref / "_index.mdx"
+ ref_md_default = md_parent / ref / "index.mdx"Line 787:
- if file_name == "_index" and content_folder == "components":
+ if file_name == "index" and content_folder == "components":Line 797:
- if file_name == "_index":
+ if file_name == "index":📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ref_md_path = md_parent / (ref + ".mdx") | |
| if ref_md_path.exists(): | |
| return ref_md_path | |
| ref_md_default = md_parent / ref / "_index.md" | |
| ref_md_default = md_parent / ref / "_index.mdx" | |
| if ref_md_default.exists(): | |
| return ref_md_default | |
| ref_md_default = Path(".") / "content" / "components" / (ref + ".md") | |
| ref_md_default = DOCS_ROOT / "components" / (ref + ".mdx") | |
| if ref_md_default.exists(): | |
| return ref_md_default | |
| return md_file # go nowhere | |
| ref_md_path = md_parent / (ref + ".mdx") | |
| if ref_md_path.exists(): | |
| return ref_md_path | |
| ref_md_default = md_parent / ref / "index.mdx" | |
| if ref_md_default.exists(): | |
| return ref_md_default | |
| ref_md_default = DOCS_ROOT / "components" / (ref + ".mdx") | |
| if ref_md_default.exists(): | |
| return ref_md_default | |
| return md_file # go nowhere |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@script/schema_doc.py` around lines 407 - 416, The fallback lookup currently
checks for "_index.mdx" and the guards compare file_name == "_index", but the
repo uses "index.mdx" so these branches never match; update the fallback in the
ref resolution (variable ref_md_default) to look for ref / "index.mdx" (and the
DOCS_ROOT components fallback to (ref + ".mdx") remains), and change the guards
that compare file_name == "_index" to compare file_name == "index" (search for
uses of md_file.stem and the variables file_name around the checks at the two
locations) so directory index pages are detected correctly.
1 participant
Description
Quick fix to get schema filled with docs from the new path and mdx extension.
Parser might need updates but with this will fix the schema gen action on https://github.com/esphome/esphome-schema/actions and get most of docs back there.
Checklist
I am merging into
nextbecause this is new documentation that has a matching pull-request in esphome as linked above.or
I am merging into
currentbecause this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.Link added in
/src/content/docs/components/index.mdxwhen creating new documents for new components or cookbook.